Django documentation

How to install Django

This document will get you up and running with Django.

Install Python

Being a Python Web framework, Django requires Python.

It works with any Python version 2.3 and higher.

Get Python at www.python.org. If you're running Linux or Mac OS X, you probably already have it installed.

Install Apache and mod_python

If you just want to experiment with Django, skip this step. Django comes with its own Web server for development purposes.

If you want to use Django on a production site, use Apache with mod_python. mod_python is similar to mod_perl -- it embeds Python within Apache and loads Python code into memory when the server starts. Code stays in memory throughout the life of an Apache process, which leads to significant performance gains over other server arrangements. Make sure you have Apache installed, with the mod_python module activated. Django requires Apache 2.x and mod_python 3.x.

See How to use Django with mod_python for information on how to configure mod_python once you have it installed.

If you can't use mod_python for some reason, fear not: Django follows the WSGI spec, which allows it to run on a variety of server platforms. See the server-arrangements wiki page for specific installation instructions for each platform.

Get your database running

If you plan to use Django's database API functionality, you'll need to make sure a database server is running. Django works with PostgreSQL (recommended), MySQL and SQLite.

Additionally, you'll need to make sure your Python database bindings are installed.

  • If you're using PostgreSQL, you'll need the psycopg package (version 1 -- not version 2, which is still in beta). If you're on Windows, check out the unofficial compiled Windows version.
  • If you're using MySQL, you'll need MySQLdb.
  • If you're using SQLite, you'll need pysqlite. Use version 2.0.3 or higher.

Install the Django code

Installation instructions are slightly different depending on whether you're using the latest official version or the latest development version.

It's easy either way.

Installing the official version

  1. Download Django-0.90.tar.gz from our download page.
  2. tar xzvf Django-0.90.tar.gz
  3. cd Django-0.90
  4. sudo python setup.py install

Note that the last command will automatically download and install setuptools if you don't already have it installed. This requires a working Internet connection.

This will install Django in your Python installation's site-packages directory.

Installing the development version

  1. Make sure you have Subversion installed.

  2. svn co http://code.djangoproject.com/svn/django/trunk/ django_src

  3. Symlink django_src/django so that django is within your Python site-packages directory:

    ln -s `pwd`/django_src/django /usr/lib/python2.3/site-packages/django

    (In the above line, change python2.3 to match your current Python version.)

You don't have to run python setup.py install.

When you want to update your code, just run the command svn update from within the django_src directory.

Comments

Nathan Colgate July 17, 2005 at 6:07 p.m.

For us Windows kids without the fancy "ln" command.

I was able to do the following:
-Download Junction (http://www.sysinternals.com/Utilities/Ju...)
-Unzip it and drop junction.exe into /windows/system32
-From the command prompt:
junction /Python24/lib/site-packages/django /django_src/django

gmwils July 18, 2005 at 6:12 a.m.

On Mac OS X, step 3 looks like:

sudo ln -s `pwd`/django_src/django /Library/Python/2.3/site-packages/django

And add the following to your path:

/Library/Python/2.3/site-packages/django/bin

As for getting mod_python to work, it looks like a build of apache from source with mod_python is required. The modpython.org website has details of this under the Docs links.

enodev July 18, 2005 at 11:56 a.m.

...and if one read those details one would find out that a re-compilation of apache is not necessary ;)

see: http://modpython.org/live/current/doc-ht...

leepro July 18, 2005 at 1:23 p.m.

hugo's advice must be in the Docs. *^^*

Army July 18, 2005 at 8:58 p.m.

On Mac OS X 10.4.2, step 3 looks like:
sudo ln -s `pwd`/django_src/django/ /Library/Frameworks/Python.framework/Versions/2.4/lib/python2.4/site-packages/django

Jeff July 19, 2005 at 9:21 a.m.

On Mac OS X, if you want to use the Fink 2.4 version of Python, here's what your link should look like:

ln -s `pwd`/django_src/django /sw/lib/python2.4/site-packages/django

Julian Hernandez Gomez (newbie) July 22, 2005 at 2:59 p.m.

Setting up Django on Debian with PostgreSQL backend

For the Brave and the impatient:

1. sudo aptitude install subversion postgresql python-psycopg
2. svn co http://code.djangoproject.com/svn/django... django_src
3. sudo ln -s `pwd`/django_src/django /usr/lib/python2.3/site-packages/django
4. sudo update-alternatives --install \
/usr/bin/django-admin.py django-admin.py \
/usr/lib/python2.3/site-packages/django/bin/django-admin.py 10
5. sudo -u postgres sh # postgresql superuser
6. sh-3.00$ createuser -A -D jhernandez # no_adduser, no_createdb
7. sh-3.00$ createdb -O jhernandez myproject # then logout (^D)
8. mkdir $HOME/devel
9. cd $HOME/devel
9. django-admin.py startproject myproject
10. export PYTHONPATH=$PYTHONPATH:$HOME/devel
11. edit myproject/settings/main.py and modify the following lines:
DATABASE_ENGINE = 'postgresql'
DATABASE_NAME = 'myproject'
DATABASE_USER = 'jhernandez'
12. django-admin.py init --settings=myproject.settings.main
13. export DJANGO_SETTINGS_MODULE=myproject.settings.main # optional

From here RTFM :-)

Brian Ray July 22, 2005 at 10:16 p.m.

I just recalled why I wrote a page on building psycopg from sources. It's a pain. So here is the link:

http://www.chipy.org/installingpsycopgon...

Hope it helps.

Moof July 23, 2005 at 10:17 a.m.

If you want to avoid all the ln business, and have the one command that works under windows too, then I suggest:

python setup.py develop

which will install a link to the django folder in a .pth file in site-packages, install django-admin.py in your system path, and still allow for svn up.

Dagur July 25, 2005 at 6:18 p.m.

you really shouldn't do that. I got this error when I tried using django-admin.py:

Traceback (most recent call last):
File "C:\pl\python24\Scripts\django-admin.py", line 3, in ?
from pkg_resources import require; require('django==1.0.0')
ImportError: No module named pkg_resources

Eric Windisch August 2, 2005 at 7:28 a.m.

bact',

Right now, they're recommending that this run underneath mod_python which is currently offered by relatively few hosts.

One host which is currently supporting Django is GrokThis.net <http://www.grokthis.net/>

David S. August 14, 2005 at 3:27 p.m.

Moof's suggstion to use 'python setup.py develop' works fine with Python 2.4 at least. I did have to open a new shell (this is Windows after all, lucky I did not have to reboot!) So Dagur's comment about 'python setup.py develop' failing is at worst only sometimes true.

Jonas August 26, 2005 at 1:46 p.m.

python setup.py develop

Worked for me on Python 2.4 / WinXP only after :

mkdir C:\python24\scripts

Tadeusz Andrzej Kadłubowski September 8, 2005 at 7:13 a.m.

Hello,

I'm a new django user just hacking in spare time (job at the horizon :]).

I got one problem with the tutorial - The reloading mechanism in the embedded web server needs sources of all needed libraries. My Linux distribution (PLD - flame me!) comes only with .pyc files. Manually installing .py sources worked fine. A hint about that in installation instructions would be nice.

As for bact's problem above: I can't see any reason why you need root privileges. Try installing all the python elements in your home directory. Or even just set PYTHONPATH to suit your needs. And use sqlite rather than complicated postgresql - sqlite is a simple library rather than a standalone daemon, which has to be set up by root.

Straw Dogs September 27, 2005 at 8:12 p.m.

Could really do with being able to use this on standard shared hosting. Was going to test it out at work and see if we could make a switch over to using it but unless we can install it without needing root privaledges then its going to be a no go for many people.

Straw Dogs Python Blog
http://blog.straw-dogs.co.uk

berlinbrown October 1, 2005 at 2:09 p.m.

I keep getting a IndexError from just setting up django? What do you think is missing. I went through the instructions, hit my site and error...

IndexError: string index out of range
args = ('string index out of range',)

43 # Append a slash if append_slash is set and the URL doesn't have a
44 # trailing slash or a file extension.
45 if settings.APPEND_SLASH and (old_url[1][-1] != '/') and ('.' not in old_url[1].split('/')[-1]):
46 new_url[1] = new_url[1] + '/'
47 if new_url != old_url:
global settings = <module 'django.conf.settings' from '/users/home...brown/public_html/spero/django/conf/settings.py'>, settings.APPEND_SLASH = True, old_url = ['www.newspiritcompany.com:8086', ''], ].split undefined

Ryan October 5, 2005 at 3:29 p.m.

To avoid Dagur's error with pkg_resources, you need to first run ez_setup.py, then do 'python setup.py develop' (both in the django-src directory).

Tim|Mac October 6, 2005 at 5:55 p.m.

If you're running Darwinports on Mac OS X and want to use sqlite, you'll need to "port install py-sqlite" (not py-sqlite2). It's the correct one.

Levi Cook October 16, 2005 at 9:31 a.m.

Re: Dagur's error with pkg_resources

Another option is to install setuptools directly
http://peak.telecommunity.com/DevCenter/...

In particular you should run...
http://peak.telecommunity.com/dist/ez_se...

Valter October 31, 2005 at 6:40 a.m.

One trick to make life easier on Windows:

- append ".py" to PATHEXT (Settings - Control Panel - System - Advanced - Environment...)
- append C:\Program Files\Python\Scripts to PATH

This way you can run django-admin.py by just typing "django-admin".

Jason Huggins November 10, 2005 at 11 p.m.

You might want to mention which versions of Python are supported (or have been tested). I think Python 2.3.x and 2.4.x is fine, but is there anything definite saying this?

Also, for those new developers coming from the Ruby, Perl, or Java worlds, you might want to briefly mention where to get and install Python itself (www.python.org)

New User November 18, 2005 at 5:36 p.m.

I used method one above (installing the official version) on OSX 10.4.3 and it seemed to work fine (no errors nothing). Except that when I try to do django-admin.py it complains it can't find it. And it seems to be installed in an ".egg" directory at least on my iBook (/Library/Python/2.3/site-packages/Django-0.90-py2.3.egg/django/bin)
Putting that in the path didn't work because it claims permission denied on django-admin. etc. etc. ad nauseam.

Seeing all the 'caveats' and ammendments to the 'official' version of the install instructions tells me there need to be more detailed instructions by platforms. Rails has that. Not that it gives it the real edge, but do I really want to piss around with little annoyances when all I'm trying to do is get the basic "look-see" going?

Just 0.2 cents from a total novice who is just trying to test drive it. Feel free to beat up on me.

Another Mac User November 22, 2005 at 8:02 p.m.

I have had the same experience as the previous poster, except I'm on Mac OS 10.3.9.

I seem to have everything installed, with django-admin.py appearing in /Library/Python/2.3/Django-0.90-py2.3.egg/bin/django-admin.py

I have added a symbolic link to django-admin.py in /usr/local/bin but when I try to follow the tutorial, I get the following error:

% django-admin.py startproject myproject
-bash: /usr/local/bin/django-admin.py: Permission denied

Any advice would be appreciated. I'm very interested in trying out Django on my Mac.

Thanks.

Joeboy November 24, 2005 at 5:25 a.m.

I might be stupid, but I was a bit confused by the fact that after following the installation guide I was still getting an error:

EnvironmentError: Could not import DJANGO_SETTINGS_MODULE 'myproject.settings' (is it on sys.path?): No module named myproject.settings

This is apparently expected behaviour, until you've gone through the tutorial and created your site.

I hope that's useful to other stupid people.

Post a comment

Note: Please only use the comments for questions/critcisms/suggestions on the docs; if you experience errors please file a ticket, ask in the IRC channel, or post to the django-users list. Comments will be periodically reviewed, integrated into the documentation proper, and removed.

Your name:

Comment: